Class Dendrogram class
The Dendrogram class encapulates most of the methods for drawing, removing,
and redrawing the dendrogram and
summary dendrogram (Some drawing methods are within the ClusterNode class.)
The constructor draws a dendrogram from the given ClusterTree.
It calls drawNode() to recursively draw the tree.
It calls setDragParams() to set up some functions as Raphael drag parameters
for the threshold bar.
It calls drawThresholdBar() to draw the threshold bar onto the graph
It calls this.gui.showThreshold() to display the threshold value
It calls this.gui.showNoOfGroups(1) to display the no of Groups value
initially as 1
Important Dendrogram attributes:
-thresholdBar - the dragable bar graphic object.
-groupList - the list of groups formed in response to a user command.
-isSummary - default false. Set to true if displaying summary dendrogram.
Some attributes are set in the constructor for tuning:
-leafLabelLength - the number of characters allowed for the leaf labels
-some thresholdBar dimensions
-some group band styling attributes
Constructor
Dendrogram class
(
cTreeIn
,
canvasIn
,
stylesIn
,
guiIn
,
axesIn
)
- Parameters:
-
cTreeIn
<ClusterTree object >
the filled cluster tree root node
-
canvasIn
<Raphael canvas object>
the Raphael canvas on which to
draw the chart
-
stylesIn
<Styles object >
various styles used in the dendrogram
such as line thickness.
-
guiIn
<Gui object >
an object giving access to user interface methods
-
axesIn
<GraphAxes object>
the axes for the graph
Methods
void
addEvents
(
nodeIn
,
guiIn
,
dendrogramIn
)
Declares event handlers for the shape using the anonymous function.
Events for:
- mouseover, or tap in iPad
- mouseout, or tap something else in iPad
- mouse click, or tap in iPad
The parameters are passed here rather than referred to by "this" even
when they are attributes local to the class because the "this" keyword
has its scope hijacked by the event. The keyword, "this",
becomes the event object during an event.
- Parameters:
-
nodeIn
<ClusterNode object>
The cluster tree node concerned.
-
guiIn
<Gui object>
the gui.
-
dendrogramIn
<object>
(Dendrogram object) the dendrogram. Needed to
avoid "this" keyword for event handling
- Returns:
void
void
addEventsToBand
(
groupIn
,
guiIn
,
dendrogramIn
)
Declares event handlers for the shape using the anonymous function.
Events for:
- mouseover, or tap in iPad
- mouseout, or tap something else in iPad
- mouse click, or tap in iPad
The parameters are passed here rather than referred to by "this" even
when they are attributes local to the class because the "this" keyword
has its scope hijacked by the event. The keyword, "this",
becomes the event object during an event.
- Parameters:
-
groupIn
<Group object>
group which contains the band for the events
-
guiIn
<Gui object>
the gui
-
dendrogramIn
<object>
(Dendrogram object) the dendrogram. Needed to
avoid "this" keyword for event handling
- Returns:
void
void
appendGroups
(
nodeIn
,
groupListIn
,
thresholdIn
)
Appends cluster groups to a list
if the nodeIn is above the threshold then call itself recursively on
childA and child B
else make a group from its descendants, append it to the list and return
- Parameters:
-
nodeIn
<Group object>
the node being examined.
-
groupListIn
<GroupList object>
the groupList to hold the
resulting groups.
-
thresholdIn
<number>
the threshold value used to define the groups.
- Returns:
void
void
applyGroupingThreshold
(
thresholdIn
)
Dendrogram_applyGroupingThreshold
1) Defines groups of leaves based on a threshold mergeHt.
2) Overlays rectangles on the dendrogram to highlight. Those clusters
below the threshold mergeHt form groups differentiated by colour
or shading of the overlayed rectangles.
3) Display the details of the groups under the Groups tab.
4) Feedback to the user via a dialoge that all this has occured.
Given a threshold number, do a depth first search to find the first
cluster below the threshold (with mergeHt < thresholdIn). The depth
first search is carried out by the appendGroups() method which calls
itself recursively. The search is started here by calling appendGroups
with the tree root node.
- Parameters:
-
thresholdIn
<number>
the threshold to be applied.
- Returns:
void
void
displayGroupList
(
groupListIn
,
messageIn
)
Outputs details of the designated group list.
Makes calls to this.displayOneGroup() and this.gui.notifyGroupFormation().
- Parameters:
-
groupListIn
<GroupList object>
an array of groups.
-
messageIn
<string>
String to preceed the display of the list
Each group is an array of leaves.
- Returns:
void
void
displayOneGroup
(
leafArrayIn
,
groupIdIn
)
Displays a single group in a div on the groups tab
by appending it to the current contents of the groups tab
- Parameters:
-
leafArrayIn
<Array of ClusterNode objects>
the leaf array which
represents the group
-
groupIdIn
<string>
a string identifier or label for the group
- Returns:
void
void
drawCluster
(
nodeIn
)
Draws a given cluster node onto the dendrogram.
- Parameters:
-
nodeIn
<ClusterNode object>
The cluster node to be drawn
- Returns:
void
void
drawClusterSummary
(
cutoffIn
,
nodeIn
)
Draws a given cluster node onto the summary dendrogram.
if the nodeIn is not the root then check parent ht (i.e. ALWAYS
draw the root)
if the xHt of the parent < cutoffIn
then set element and bounding box to null and return
else
set element and bounding box to null
set the left hand end to be the cutoffIn Ht and draw the new cluster
- Parameters:
-
cutoffIn
<number>
the Ht at which the graph is truncated
-
nodeIn
<ClusterNode object>
The cluster node to be drawn.
- Returns:
void
void
drawGroupBands
(
groupListIn
)
Loops through the given group list drawing bands on the graph. It
alternates styling to create banding.
Makes calls on this.drawOverlayBand()
- Parameters:
-
groupListIn
<GroupList object>
an array of groups.
- Returns:
void
boolean
drawLeaf
(
nodeIn
)
Draws a leaf graphic element
- Parameters:
-
nodeIn
<ClusterNode object>
The node describing the leaf
- Returns:
boolean
- but value not used
void
drawLeafLabel
(
nodeIn
)
Draws a text element on the graph next to the leaf.
- Parameters:
-
nodeIn
<ClusterNode object>
The node describing the leaf
- Returns:
void
void
drawLeafSummary
(
nodeIn
,
cutoffIn
)
Draws a leaf graphic element for the Summary dendrogram. Summary leaves are
different to those on the normal chart. They have no base and vary
in length if they are to be drawn at all.
If the xHt of the parent < cutoffIn then set element to null and return
else
set the left hand end to be the cutoffIn Ht and draw the leaf
- Parameters:
-
nodeIn
<ClusterNode object>
The node describing the leaf (a Node)
-
cutoffIn
<number>
the Ht at which the graph is truncated
- Returns:
void
boolean
drawNode
(
nodeIn
)
Draws the tree by starting with the root node and recursively
calling itself.
Makes calls on this.drawCluster(), this.drawLeaf() and this.drawLeafLabel().
- Parameters:
-
nodeIn
<ClusterNode object>
the node to be drawn
- Returns:
boolean
- but value not used.
Boolean
drawNodeSummary
(
nodeIn
,
cutoffIn
)
Draws the summary tree by starting with the root node and recursively
calling itself
Makes calls on this.drawClusterSummary() and this.drawLeafSummary().
- Parameters:
-
nodeIn
<ClusterNode object>
the node to be drawn
-
cutoffIn
<number>
the mergeHt below which nothing is to be drawn
- Returns:
Boolean
- but value not used.
void
drawOverlayBand
(
groupListIn
,
the
)
Takes a group and draws an overlay on the graph to delineate it.
The band is a rectangle of length (the X dimension), thresholdIn.
Its top and bottom (the Y dimension) defined by groupIn.topBound and
groupIn.bottomBound
Makes a call on this.addEventsToBand().
- Parameters:
-
groupListIn
<Group object>
an array of leaves.
-
the
<number>
threshold defining the groups
- Returns:
void
void
drawSummary
(
)
Draws a summary dendrogram truncated at the current threshold ht.
1) record the cutoff Ht from the threshold pos
2) clear the canvas by removing the paper object
3) set a new xaxis scale factor
4) create a new paper object of appropriate size
5) draw new axes
6) draw the summary dendrogram taking into account the cutoff
Boolean
drawThresholdBar
(
)
Draws the dragable threshold adjuster bar
- Returns:
Boolean
- but value not used.
number
getThresholdPos
(
barIn
)
Detects the threshold bar position and returns that in terms of the xaxis
merge Ht.
Makes a call on this.canvas.getGraphXfromCvX().
- Parameters:
-
barIn
<graphic object>
The threshold bar whose pos is to be detected
- Returns:
number
- the xPos of the bar
void
removeAll
(
)
Removes all of the drawn elements including the axes
void
removeGroups
(
)
Removes the groups from the dendrogram
1) reset the grouplist
2) reset the threshold to max and its field
3) reset group no field to 1
4) undraw the bands
Makes calls on gui methods and the this.groupList.reset() method.
void
restore
(
)
Redraws the dendrogram after displaying truncated graph
1) clear the canvas by removing the paper object
2) resets the canvas originHt to 0
4) create a new paper object of appropriate size
5) draw new axes
6) draw the dendrogram
void
setDragParams
(
canvasIn
,
guiIn
)
Sets Dendrogram properties to serve as parameters for the
Raphael drag() method.
Based on Dmitry's Graffle example http://raphaeljs.com/graffle.html
Makes a call on guiIn.showThreshold().
- Parameters:
-
canvasIn
<Canvas object>
The canvas
-
guiIn
<Gui object>
The gui
- Returns:
void
number
setThresholdBarToLess
(
fractionIn
)
Sets the threshold bar to one step down the
merge Ht.
- Parameters:
-
fractionIn
<number>
the fraction of the full travel to make each step
e.g. 20 means each step is 1/20th of the full travel
- Returns:
number
- the Merge Ht value of the new threshold position
number
setThresholdBarToMatch
(
thresholdIn
)
Sets the threshold bar position in response to some other control
- Parameters:
-
thresholdIn
<number>
the threshold to set
- Returns:
number
- the Merge Ht value of the new threshold position
number
setThresholdBarToMax
(
)
Sets the threshold bar to the maximum
merge Ht.
- Returns:
number
- the Merge Ht value of the new threshold position
number
setThresholdBarToMore
(
fractionIn
)
Sets the threshold bar to one step up the
merge Ht.
- Parameters:
-
fractionIn
<number>
the fraction of the full travel to make each step
e.g. 20 means each step is 1/20th of the full travel
- Returns:
number
- the Merge Ht value of the new threshold position
setThresholdBarToZero
(
)
Sets the threshold bar to zero (or the origin Ht in the case of Summary graph)
void
setThresholdForNoOfGroups
(
noOfGroupsIn
)
Sets the threshold to be one which will give the required no of groups.
Takes the given no of groups and by a binary search sucessively applies a
new threshold until it finds one that fits the required no of groups and
leaves the threshold bar set there.
The binary search is limited to 75 iterations if it does not find the right
spot by then it stops and returns the nearest no of groups it could get.
Group formation can fail to achieve the number of requested groups. There
are 4 ways this can occur
1) after 75 binary search iterations if some data set had many many
clusters at very similar hieghts, it might be that the requested
no. of groups was not reachable, due to running out of iterations.
I recon this is highly unlikely at 75 iterations.
2) An impossible number of groups was requested (maybe a decimal, or
less than 1, or greater than the number of leaves
3) if there are any leaves which merge at Ht zero then these cannot be
allocated to separate groups. They must share a group with their
zero Ht cluster mate.
4) if creating groups on a summary graph then if the threshold would
need to be below the cutoff to create the requested number of groups
then it won't go below the cutoff Ht.
Makes a call on:
this.displayGroupList()
this.drawGroupBands()
this.setThresholdBarToMatch()
this.gui.showThreshold()
and
this.gui.showNoOfGroups()
Also makes calls on a number of GroupList methods
- Parameters:
-
noOfGroupsIn
<number>
the required no of groups
- Returns:
void
void
styleCluster
(
nodeIn
)
Styles a given cluster
- Parameters:
-
nodeIn
<ClusterNode object>
The cluster node to style (a Node)
- Returns:
void
void
styleLeaf
(
nodeIn
)
Styles a given leaf
- Parameters:
-
nodeIn
<ClusterNode object>
The leaf node to style
- Returns:
void